.. _cmmIxLine:

cmmIxLine
==========
----------

SYNOPSIS
```````````

.. code-block:: none

    VT_I4 cmmIxLine(
        [in] VT_I4 MapIndex, [in] VT_PR8 DistList, [in] VT_I4 IsBlocking
        )


DESCRIPTION
`````````````

- 이 함수는 현재 위치로부터의 상대 좌표로의 직선 보간 이동을 수행합니다. cmmIxLine() 함수는 모션이 완료되기
  전까지 반환되지 않으며, cmmIxLineStart() 함수는 모션을 시작시킨 후에 바로 반환됩니다.

PARAMETER
`````````````

- MapIndex : 맵번호(Map index), 이 맵번호를 사용하기전에 먼저 cmnIxMapAxes() 함수를 통하여 해당 맵번호에
  유효한 축들이 맵핑되어 있어야 합니다.

\

- DistList : 현재 위치로부터의 상대적인 이동 좌표값(각 축의 이동 거리값)의 배열 주소. 이 배열의 크기는
  cmnIxMapAxes() 함수를 통하여 맵핑된 축의 수와 일치하여야 합니다. 거리의 단위는 “Unit distance”에 의해 정의되는
  논리적 거리를 적용합니다.

\

- IsBlocking : 완료될 때까지 기다리는 동안 윈도우 메시지를 블록(Blocking)할 것인지를 결정합니다. 

.. csv-table::
    :widths: 10 85
    :header-rows: 1
    :stub-columns: 0

    Value, Meaning
    cmFALSE, 블록(Blocking)을 하지 않습니다. 따라서 해당 모션이 완료되는 동안에도 윈도우 이벤트를 처리합니다.
    cmTRUE, 블록(Blocking)을 합니다. 따라서 해당 모션이 완료되는 동안에는 윈도우 이벤트가 처리되지 않습니다.


RETURN VALUE
`````````````

+--------------+-----------+
| Value        | Meaning   |
+==============+===========+
| 음수         | 수행 실패 |
+--------------+-----------+
| cmERR_NONE   | 수행 성공 |
+--------------+-----------+


REFERENCE
```````````

- 논리적 거리 단위는 cmmCfgSetUnitDist() 함수에 의해 결정됩니다.

\

- cmmIxLineStart() 함수를 사용하는 경우에는 cmmIxIsDone() 함수나 cmmIxWaitDone() 함수를 사용하여 모션의
  완료를 확인할 수 있습니다.

\

- cmmIxLine() 함수를 사용하는 경우에는 INP 입력신호가 Enable 로 설정되었으면 Command 펄스 출력이
  완료되어도 INP 입력이 ON 이 되기 전까지는 모션이 완료되지 않은 것으로 간주되어 반환되지 않습니다. 
  스탭 드라이브는 INP 출력이 없는 경우가 일반적인데, 고객님의 부주의나 잘못된 설정으로 INP 입력에 대한
  설정이 Enable 로 되어 있을 경우 INP 입력이 스탭 드라이브를 통해 발생하지 않는 이유 때문에 모션 완료가 되지
  않는 경우가 발생할 수 있습니다.
  고객 여러분들께서는 스탭 드라이브 사용시에 이점을 주의해주시기를 부탁드립니다.


.. note:: 윈도우 이벤트라는 것은 무엇입니까?
    윈도우 운영체제는 Event Driven 혹은 Message Driven 방식3의 구조로 되어
    있습니다. 각 응용프로그램은 메시지 큐(Queue)를 가지고 있으며, 정확히 말하면, 
    메시지를 사용해 이벤트를 통지하는 방식으로 설계되어 있습니다. 윈도우
    메시지를 처리한다는 것은 메시지 큐에서 메시지를 하나씩 꺼내서 윈도우
    프로시저에 전송한다는 것을 의미하며, 이것은 그 행선지가 되는 윈도우에
    전송되어 처리됩니다.


EXAMPLE
```````````

.. code-block:: c++
 :linenos:
 :emphasize-lines: 5

 C/C++ 

 #include "Cmmsdk.h"
 #include "CmmsdkDef.h"
 
 /***************************************************************
 * OnProgramInitial : 이 함수는 가상의 함수로서 프로그램 초기화 루틴이
 * 적용되는 부분을 의미합니다.
 ***************************************************************/
 void OnProgramInitial()
 {
    long m_nNumAxes;
    cmmLoadDll();
    if(cmmGnDeviceLoad(cmTRUE, &m_nNumAxes) != cmERR_NONE)
    {
        //Handle 은 사용자가 생성한 폼의 핸들 값입니다.
        cmmErrShowLast(Handle);
        return;
    }
 }
 
 /***************************************************************
 * OnSetSpeed : 이 함수는 속도설정의 변경이 필요할 때
 * 호출되는 가상의 함수 입니다. 
 ***************************************************************/
 #define MAP0 0 //맵번호 (0)
 void OnSetSpeed()
 {
    cmmIxMapAxes(MAP0, cmX1_MASK | cmY1_MASK, 0 );
    //또는 cmmIxMapAxes(MAP0, 0x3, 0x0); 
    //보간 이동할 축들의 기본속도를 설정합니다.
    cmmCfgSetSetSpeedPattern(cmX1, cmSMODE_T, 1000, 5000, 5000);
    cmmCfgSetSetSpeedPattern(cmY1, cmSMODE_T, 1000, 5000, 5000);
 }
 
 /***************************************************************
 * DoMotion : 작업명령시에 호출되는 가상의 함수 입니다. 
 * 이 함수는 X1, Y1 축에 대하여 (1000, 2000)만큼 이동한 후 다시 
 * (-1000, -2000)만큼 이동을 수행합니다. 
 ***************************************************************/
 void DoMotion()
 {
    double fDistList[2] = {1000, 2000};//각축의 이동할 거리입니다.
   
    //MAP0 를 마스터 속도 모드, Trapezoidal 속도 패턴으로 작업속도의 100%,
    //가속도의 70%, 감속도의 70%로 설정 합니다.
    cmmIxSetSpeedPattern(MAP0, cmFALSE, cmSMODE_T, 100, 70, 70 );
    cmmIxLine(MAP0, fDistList, cmFALSE);
    fDistList[0] = -1000; fDistList[1] = -2000;
    cmmIxLine(MAP0, fDistList, cmFALSE);
   
    //cmmIxLineStart() 함수를 사용하는 경우에는 다음과 같이 코드를 작성합니다.
    //double fDistList[2] = {1000, 2000};
    //cmmIxSetSpeedPattern(MAP0, cmFALSE, cmSMODE_T, 100, 70, 
    //70 );
    //cmmIxLineStart(MAP0, fDistList);
    //cmmIxWaitDone(MAP0, cmFALSE);
    //fDistList[0] = -1000; fDistList[1] = -2000;
    //cmmIxLineStart(MAP0, fDistList);
    //cmmIxWaitDone(MAP0, cmFALSE);
 } 


.. code-block:: none
 :linenos:

 Visual Basic

 ‘맵 번호 MAP0 은 이미 선언되어 있다고 가정함.
 ‘=============================================================
 ‘cmmGnDeviceLoad 함수로 장치를 초기화 합니다.
 ‘=============================================================

 Private Sub Form_Load()
    Dim nTotalAxis As Long
    Dim IRetVal As Long 
 '=============================================================
 ' cmmGnDeviceLoad 함수로 장치를 초기화합니다.
  IRetVal = cmmGnDeviceLoad(cmTRUE, nTotalAxis)
 
  If IRetVal <> cmERR_NONE Then
    MsgBox ("cmmGnDeviceLoad has been failed")
  End If 
  '=============================================================
 End Sub

 ' 직선 보간제어 이송을 시작합니다.
 Private Sub btnMove_Click()
 
    Dim DistanceList(2) As Double
    Dim nRetVal As Long
 
     DistanceList(0) = 1000
    DistanceList(1) = 2000
 
    ' ===========================================================
    ' cmmIxMapAxes 함수는 다음과 같은 인자를 필요로 합니다. '
    ' cmmIxMapAxes(맵번호, 비트(Bit)를 통한 맵구성 #1, 비트(Bit)를 통한 맵구성 #2 
    ' ==========================================================
    
  nRetVal = cmmIxMapAxes(MAP0, &H3, &H0)
  ' /////////////////////////////////////////////////////////// 
  If cmmIxSetSpeedPattern(MAP0, cmFALSE, cmSMODE_S, 100, 100, _
        100) <> cmERR_NONE Then
 
    ' 아래와 같은 커미조아 CMMSDK 전용 에러 표시 함수를
    ‘ 사용할 수 있습니다.
    ' cmmErrShowLast (IxLine.Hwnd)
    ' -------------------------------------------------------
    MsgBox ("cmmIxSetSpeedPattern has been failed")
  End If
 
  ' cmmIxLine 함수를 통해 선형 보간을 수행합니다. 인자는 순서대로, 맵번호, 
      ‘ 거리정보를 가지고 있는 배열, 블록 여부 입니다.
  nRetVal = cmmIxLine(MAP0, DistanceList(0), cmFALSE) 
 End Sub

 Private Sub CfgSpeed(nTotalAxis As Long)
  Dim i As Integer
  '==============================================================
  ' 이 함수에서 cmmCfgSetSpeedPattern 함수로 속도를 설정하는 것은 모든 모션의 기준속도(Standard
  ' Speed) 가 됩니다.
  ' 단축 구동을 비롯한 대부분의 모션 동작은 이 기준 속도의 비율로 동작되게 됩니다.
  ' 아래 함수는 전체 축에 대해서 임의의 기준 속도를 설정하고 있습니다.
  '=============================================================
 
  For i = 0 To nTotalAxis-1
    Call cmmCfgSetSpeedPattern(0, cmSMODE_S, 1000, 2000, 2000)
  Next 
 End Sub


.. code-block:: none
 :linenos:

 Delphi

 Const MAPINDEX = 0;
 // * 이 함수는 폼이 생성될때 이벤트에 의해 불려지며 , 장치를 로드하는 함수입니다.

 procedure OnCreate();
 var
    g_nAxis : LongInt;
 begin
    // Load CMMSDK(DLL) Library
    if ( cmmGnDeviceLoad(cmTRUE,@g_nAxis) <> cmERR_NONE ) then
    begin
        // 마지막에 발생한 에러를 화면에 표시합니다.
        // 함수 인자로는 Form 의 Handle 이 전달됩니다.
        cmmErrShowLast(Form1.Handle);
        exit; 
    end
 end;

 // * Description : 구동 속도를 설정합니다.
 procedure btnSetSpeedClick();
 var
    fAccelSpeed : Double;
    fDecelSpeed : Double;
    fWorkSpeed : Double;
    nSMODE : LongInt;

 begin
 
    fAccelSpeed := 50000;
     fDecelSpeed := 50000;
    fWorkSpeed := 10000;
    nSMODE := cmSMODE_S;

     // cmX1 을 위해 설정된 기준 속도를 실제 SDK 함수에 전달합니다.
    // cmY1 을 위해 설정된 기준 속도를 실제 SDK 함수에 전달합니다.
 
    // 이 예제에서는 보간제어의 속도가 [Master 속도 모드]일때
    // 거리에 따라서, Slave 축이 최대속도를 초과하는 경우
    // Master 축의 속도는 자동으로 조절되어, 
    // Slave 축의 속도 초과 문제를 해결합니다.
    cmmCfgSetSpeedPattern(
    cmX1, // Master 축의 축 번호입니다.
    nSMODE, // 가감속이 없는 모드와 선형 가감속, S-CURVE 가감속을 설정합니다.
    fWorkSpeed, // 작업 속도를 설정합니다.
    fAccelSpeed, // 가속도를 설정합니다.
    fDecelSpeed); // 감속도를 설정합니다.
 
    // 이때 아래 설정되는 Slave 축의 기준 속도(Standard Speed) 는
    // Slave 축의 최대 속도가 됩니다.
    // 이 최대 속도에 의해서 Master 속도모드에서 계산된 Master 축의
    // 속도는 자동으로 조절이됩니다.
    cmmCfgSetSpeedPattern(
    cmY1, // Slave 축의 축 번호입니다.
    nSMODE, // 가감속이 없는 모드와 선형 가감속, S-CURVE 가감속을 설정합니다.
    1000, // 작업 속도를 설정합니다.
    2000, // 가속도를 설정합니다.
    2000); // 감속도를 설정합니다.
 
  end;

 // * Description :
 // *
 // * 상대 좌표를 목표 위치로 하여 직선 보간을 수행합니다.
 // *

 procedure btnMoveClick();
 var

     AxisList : Array[0..1] of LongInt;
    fDistanceList : Array[0..1] of Double;
 
 begin
    // cmmIxMapAxes 함수로 보간제어에 해당하는 축을
    // 그룹(Group)화 합니다.
    // $3 의 의미는 Delphi 에서 0x3 을 의미하며, 해당 축의 구성은
    // 개별 비트를 의미합니다. 즉 1 번째 비트와 2 번째 비트를 의미하며,
    // 해당 비트를 16 진수로 보았을 때에는 0x3 이 됩니다.
    cmmIxMapAxes(MAPINDEX,$3,$0);
 
    // -------------------------------------------------------
    // 보간제어의 속도 모드에 대해서 다음과 같이 설정할 수 있습니다.

    // 아래는 Vecter Speed 모드로 동작하는 예제입니다.
    //cmmIxSetSpeedPattern(MAPINDEX, cmTRUE, cmSMODE_S, 1000, 2000, 2000);

    // 아래는 Master Speed 모드로 동작하는 예제입니다.
    // Master Speed 설정
    // 가속도 : 100%
    // 감속도 : 100%
    // 작업속도 : 100%
 
     cmmIxSetSpeedPattern(MAPINDEX, cmFALSE, cmSMODE_S,
            100,100,100);
    
    // -------------------------------------------------------

     AxisList[0] := cmX1;
    AxisList[1] := cmY1;
 
    fDistanceList[0] := 1000;
    fDistanceList[1] := 1000;

     // 보간 대상 그룹을 통해 실제 보간 작업을 수행합니다.
    // 이때 함수의 이름을 통해
    // cmmIxLine 은 상대 좌표 보간을 의마힙니다. 
    // 직선 보간이 완료된 후 반환됩니다.
    // cmmIxLineTo 는 절대 좌표 보간을 의미합니다. 
    // 직선 보간이 완료된 후 반환됩니다.
    // cmmIxLineStart / cmmIxLineToStart 는 각각 상대좌표와 절대 좌표를
    // 목적 위치로 하여,
    // 직선 보간이 시작되자 마자 바로 반환합니다.
    cmmIxLine(MAPINDEX, @fDistanceList, cmFALSE);

 end;


.. seealso:: :ref:`cmmIxLineStart`, :ref:`cmmIxLineTo`, :ref:`cmmIxLineToStart`